home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1999 October: Technology Seed / ADC Seed CD - October 1999.toast / FireWire / FireWire_2.0_SDK / Interfaces / FireWireSBP2.h < prev    next >
Encoding:
C/C++ Source or Header  |  1999-04-12  |  12.0 KB  |  455 lines  |  [TEXT/MPS ]
  1. /*
  2.     File:        FireWireSBP2.h
  3.  
  4.     Contains:    Public API for Serial Bus Protocol 2 (SBP-2)
  5.  
  6.     Version:    1.0
  7.  
  8.     Copyright:    © 1998-1999 by Apple Computer, Inc., all rights reserved.
  9.  
  10.     File Ownership:
  11.  
  12.         DRI:                Eric Anderson
  13.  
  14.         Other Contact:        
  15.  
  16.         Technology:            FireWire
  17.  
  18.     Writers:
  19.  
  20.         (EA)    Eric Anderson (ewa)
  21.         (CP)    Collin Pieper
  22.         (DCB)    Clinton Bauder
  23.  
  24.     Change History (most recent first):
  25.  
  26.       <FW13>     2/22/99    EA        Removed DeviceNotify.h.
  27.       <FW12>     2/15/99    DCB        Roll-in Eric's changes.
  28.     <FW11a1>      2/7/99    EA        Added kSBP2NormalCommandReset.  Added generation flag/service
  29.                                     for normal command objects.  On a branch because the new
  30.                                     services are also on a branch.
  31.       <FW11>      1/7/99    CP        Fix typo in FWGetSBP2CommandLUN definition
  32.       <FW10>      1/3/99    EA        Added enum for four ORB types (normal, reserved, vendor, and
  33.                                     dummy).
  34.        <FW9>      1/3/99    EA        Changed pPassword from double to single pointer in Get/Set
  35.                                     functions for Logins.
  36.        <FW8>      1/3/99    EA        Added FWGetSBP2NormalCommandObjectFromORB_POINTER.
  37.        <FW7>      1/3/99    EA        Added FWSetSBP2CommandLUN and FWGetSBP2CommandLUN prototypes.
  38.        <FW6>    12/31/98    EA        Removed obsolete kSBP2TerminateTask and kSBP2ClearTaskSet.
  39.        <FW5>    11/18/98    EA        Added command object ID to notification structure. Added
  40.                                     routines to access clientData (refCon).
  41.        <FW4>    11/15/98    EA        Added prototype for FWGetSBP2LUNFromFWReferenceID.
  42.        <FW3>    10/28/98    DCB        Added structures for DFMDescriptor matching of SBP2 devices.
  43.        <FW2>     9/20/98    EA        Filled in header comments.
  44.        <FW1>     9/20/98    EA        first checked in
  45. */
  46.  
  47.  
  48.  
  49. #ifndef __FIREWIRESBP2__
  50. #define __FIREWIRESBP2__
  51.  
  52. #ifndef __TYPES__
  53. #include <Types.h>
  54. #endif
  55. #ifndef __NAMEREGISTRY__
  56. #include <NameRegistry.h>
  57. #endif
  58. #ifndef __FIREWIRE__
  59. #include <FireWire.h>
  60. #endif
  61.  
  62. #ifdef __cplusplus
  63. extern "C" {
  64. #endif
  65.  
  66. #if PRAGMA_IMPORT_SUPPORTED
  67. #pragma import on
  68. #endif
  69.  
  70. #if PRAGMA_ALIGN_SUPPORTED
  71. #pragma options align=power
  72. #endif
  73.  
  74. ////////////////////////////////////////////////////////////////////////////////
  75. //
  76. // DFM structures for SBP2.
  77. //
  78.  
  79. struct SBPDFMDataStruct
  80. {
  81.     UInt32                vendorID;
  82.     UInt32                softwareRev;
  83.     UInt32                firmwareRev;
  84.     UInt32                LUN;
  85.     UInt32                devType;
  86. };
  87. typedef struct SBPDFMDataStruct
  88.                         SBPDFMData,
  89.                         *SBPDFMDataPtr;
  90.  
  91. struct SBPMatchDataStruct
  92. {
  93.     UnsignedWide            vendorID;
  94.     UnsignedWide            softwareRev;
  95.     UnsignedWide            firmwareRev;
  96.     UnsignedWide            LUN;
  97.     UnsignedWide            devType;
  98. };
  99. typedef struct SBPMatchDataStruct
  100.                             SBPMatchData,
  101.                             *SBPMatchDataPtr;
  102.  
  103.  
  104. ////////////////////////////////////////////////////////////////////////////////
  105. //
  106. // Public FireWire SBP-2 defs.
  107. //
  108.  
  109. // Login command object option flags:
  110.  
  111. enum
  112. {
  113.     kSBP2NotifyOnLoginComplete            = (1 << 0),
  114.     kSBP2NotifyOnLoginFailed            = (1 << 1),
  115.     kSBP2NotifyOnReconnecting            = (1 << 2),
  116.     kSBP2NotifyOnReconnectComplete        = (1 << 3),
  117.     kSBP2NotifyOnReconnectFailed        = (1 << 4),
  118.     kSBP2ExclusiveLogin                    = (1 << 5)
  119. };    
  120.  
  121.  
  122. // Notification events:
  123.  
  124. enum
  125. {
  126.     kSBP2LoginComplete                    = 1,
  127.     kSBP2LoginFailed                    = 2,
  128.     kSBP2Reconnecting                    = 3,
  129.     kSBP2ReconnectComplete                = 4,
  130.     kSBP2ReconnectFailed                = 5,
  131.     kSBP2NormalCommandStatus            = 6,
  132.     kSBP2NormalCommandTimeout            = 7,
  133.     kSBP2UnsolicitedStatus                = 8,
  134.     kSBP2NormalCommandReset                = 9
  135. };    
  136.  
  137.  
  138. // Normal command object option flags:
  139.  
  140. enum
  141. {
  142.     kSBP2CommandCompleteNotify            = (1 << 0),
  143.     kSBP2CommandTransferDataFromTarget    = (1 << 1),
  144.     kSBP2CommandImmediate                = (1 << 2),
  145.     kSBP2Command64BitBufferAddresses    = (1 << 3),
  146.     kSBP2CommandContiguousBuffers        = (1 << 4),
  147.     kSBP2CommandNormalORB                = (1 << 5),
  148.     kSBP2CommandReservedORB                = (1 << 6),
  149.     kSBP2CommandVendorORB                = (1 << 7),
  150.     kSBP2CommandDummyORB                = (1 << 8),
  151.     kSBP2CommandCheckGeneration            = (1 << 9)
  152. };    
  153.  
  154.  
  155. // Function codes for Management ORBs.  Not all codes are available to drivers.
  156. // (Login, Reconnect, Logout are used automatically - do not try to use these.)
  157.  
  158. enum
  159. {
  160.     kSBP2Login                            = 0,
  161.     kSBP2QueryLogins                    = 1,
  162.     kSBP2Reconnect                        = 3,
  163.     kSBP2SetPassword                    = 4,
  164.     kSBP2Logout                            = 7,
  165.     kSBP2AbortTask                        = 0xB,
  166.     kSBP2AbortTaskSet                    = 0xC,
  167.     kSBP2LogicalUnitReset                = 0xE,
  168.     kSBP2TargetReset                    = 0xF
  169. };    
  170.  
  171.  
  172. struct FWClientSBP2NotifyParamsStruct
  173. {
  174.     FWClientInterfaceParams        fwClientInterfaceParams;            // common params
  175.     FWCommandObjectID            fwCommandObjectID;
  176.     UInt32                        notificationEvent;
  177.     Ptr                            message;
  178.     UInt32                        length;
  179.     Ptr                            loginResponse;
  180.     UInt32                        notificationProcData;
  181.     UInt32                        generation;
  182. };
  183. typedef struct FWClientSBP2NotifyParamsStruct
  184.                                 FWClientSBP2NotifyParams,
  185.                                 *FWClientSBP2NotifyParamsPtr;
  186.     
  187. typedef OSStatus (FWClientSBP2NotifyProc) (
  188.     FWClientSBP2NotifyParamsPtr    pFWClientSBP2NotifyParams,
  189.     UInt32                        *pCommandAcceptance);
  190. typedef FWClientSBP2NotifyProc    *FWClientSBP2NotifyProcPtr;
  191.  
  192.  
  193. ////////////////////////////////////////////////////////////////////////////////
  194. //
  195. // Public FireWire SBP-2 API.
  196. //
  197.  
  198. OSStatus    FWAllocateSBP2LoginCommandObject (
  199.     FWReferenceID                fwReferenceID,
  200.     FWCommandObjectID            *pFWCommandObjectID);
  201.  
  202. OSStatus    FWSetSBP2LoginCommandPassword (
  203.     FWCommandObjectID            fwCommandObjectID,
  204.     Ptr                            password,
  205.     UInt32                        length);
  206.  
  207. OSStatus    FWGetSBP2LoginCommandPassword (
  208.     FWCommandObjectID            fwCommandObjectID,
  209.     Ptr                            password,
  210.     UInt32                        *pLength);
  211.  
  212. OSStatus    FWSetSBP2LoginCommandFlags (
  213.     FWCommandObjectID            fwCommandObjectID,
  214.     UInt32                        loginFlags);
  215.  
  216. OSStatus    FWGetSBP2LoginCommandFlags (
  217.     FWCommandObjectID            fwCommandObjectID,
  218.     UInt32                        *pLoginFlags);
  219.  
  220. OSStatus    FWSetSBP2LoginCommandMaxPayloadSize (
  221.     FWCommandObjectID            fwCommandObjectID,
  222.     UInt32                        maxPayloadSize);
  223.  
  224. OSStatus    FWGetSBP2LoginCommandMaxPayloadSize (
  225.     FWCommandObjectID            fwCommandObjectID,
  226.     UInt32                        *pMaxPayloadSize);
  227.  
  228. OSStatus    FWSetSBP2LoginCommandLoginNotifyProc (
  229.     FWCommandObjectID            fwCommandObjectID,
  230.     FWClientSBP2NotifyProcPtr    notificationProc,
  231.     UInt32                        notificationProcData);
  232.  
  233. OSStatus    FWGetSBP2LoginCommandLoginNotifyProc (
  234.     FWCommandObjectID            fwCommandObjectID,
  235.     FWClientSBP2NotifyProcPtr    *pNotificationProc,
  236.     UInt32                        *pNotificationProcData);
  237.  
  238. OSStatus    FWSetSBP2LoginCommandStatusNotifyProc (
  239.     FWCommandObjectID            fwCommandObjectID,
  240.     FWClientSBP2NotifyProcPtr    notificationProc,
  241.     UInt32                        notificationProcData);
  242.  
  243. OSStatus    FWGetSBP2LoginCommandStatusNotifyProc (
  244.     FWCommandObjectID            fwCommandObjectID,
  245.     FWClientSBP2NotifyProcPtr    *pNotificationProc,
  246.     UInt32                        *pNotificationProcData);
  247.  
  248. OSStatus    FWSetSBP2LoginCommandUnsolicitedStatusNotifyProc (
  249.     FWCommandObjectID            fwCommandObjectID,
  250.     FWClientSBP2NotifyProcPtr    notificationProc,
  251.     UInt32                        notificationProcData);
  252.  
  253. OSStatus    FWGetSBP2LoginCommandUnsolicitedStatusNotifyProc (
  254.     FWCommandObjectID            fwCommandObjectID,
  255.     FWClientSBP2NotifyProcPtr    *pNotificationProc,
  256.     UInt32                        *pNotificationProcData);
  257.  
  258. OSStatus    FWSetSBP2LoginCommandParams (
  259.     FWCommandObjectID            fwCommandObjectID,
  260.     Ptr                            password,
  261.     UInt32                        length,
  262.     UInt32                        loginFlags,
  263.     UInt32                        maxPayloadSize,
  264.     FWClientSBP2NotifyProcPtr    loginNotificationProc,
  265.     FWClientSBP2NotifyProcPtr    statusNotificationProc,
  266.     FWClientSBP2NotifyProcPtr    unsolicitedStatusNotificationProc,
  267.     UInt32                        notificationProcData);
  268.  
  269. OSStatus    FWGetSBP2LoginCommandParams (
  270.     FWCommandObjectID            fwCommandObjectID,
  271.     Ptr                            password,
  272.     UInt32                        *pLength,
  273.     UInt32                        *pLoginFlags,
  274.     UInt32                        *pMaxPayloadSize,
  275.     FWClientSBP2NotifyProcPtr    *pLoginNotificationProc,
  276.     FWClientSBP2NotifyProcPtr    *pStatusNotificationProc,
  277.     FWClientSBP2NotifyProcPtr    *pUnsolicitedStatusNotificationProc);
  278.  
  279. OSStatus    FWSetSBP2CommandLUN (
  280.     FWCommandObjectID            fwCommandObjectID,
  281.     UInt32                        logicalUnitNumber);
  282.  
  283. OSStatus    FWGetSBP2CommandLUN (
  284.     FWCommandObjectID            fwCommandObjectID,
  285.     UInt32                        *pLogicalUnitNumber);
  286.  
  287. OSStatus    FWAllocateSBP2NormalCommandObject (
  288.     FWCommandObjectID            fwLoginCommandObjectID,
  289.     FWCommandObjectID            *pFWCommandObjectID);
  290.  
  291. OSStatus    FWSetSBP2NormalCommandBuffers (
  292.     FWCommandObjectID            fwCommandObjectID,
  293.     UInt32                        bufferCount,
  294.     FWAddress                    *bufferPtrList,
  295.     UInt32                        *bufferLengthList);
  296.  
  297. OSStatus    FWGetSBP2NormalCommandBuffers (
  298.     FWCommandObjectID            fwCommandObjectID,
  299.     UInt32                        *pBufferCount,
  300.     FWAddress                    *bufferPtrList,
  301.     UInt32                        *bufferLengthList);
  302.  
  303. OSStatus    FWSetSBP2NormalCommandCommand (
  304.     FWCommandObjectID            fwCommandObjectID,
  305.     Ptr                            commandBuffer,
  306.     UInt32                        commandLength);
  307.  
  308. OSStatus    FWGetSBP2NormalCommandCommand (
  309.     FWCommandObjectID            fwCommandObjectID,
  310.     Ptr                            commandBuffer,
  311.     UInt32                        *pCommandLength);
  312.  
  313. OSStatus    FWSetSBP2NormalCommandFlags (
  314.     FWCommandObjectID            fwCommandObjectID,
  315.     UInt32                        normalFlags);
  316.  
  317. OSStatus    FWGetSBP2NormalCommandFlags (
  318.     FWCommandObjectID            fwCommandObjectID,
  319.     UInt32                        *pNormalFlags);
  320.  
  321. OSStatus    FWSetSBP2NormalCommandMaxPayloadSize (
  322.     FWCommandObjectID            fwCommandObjectID,
  323.     UInt32                        maxPayloadSize);
  324.  
  325. OSStatus    FWGetSBP2NormalCommandMaxPayloadSize (
  326.     FWCommandObjectID            fwCommandObjectID,
  327.     UInt32                        *pMaxPayloadSize);
  328.  
  329. OSStatus    FWSetSBP2NormalCommandTimeout (
  330.     FWCommandObjectID            fwCommandObjectID,
  331.     Duration                    timeoutDuration);
  332.  
  333. OSStatus    FWGetSBP2NormalCommandTimeout (
  334.     FWCommandObjectID            fwCommandObjectID,
  335.     Duration                    *pTimeoutDuration);
  336.  
  337. OSStatus    FWSetSBP2NormalCommandClientData (
  338.     FWCommandObjectID            fwCommandObjectID,
  339.     UInt32                        clientData);
  340.  
  341. OSStatus    FWGetSBP2NormalCommandClientData (
  342.     FWCommandObjectID            fwCommandObjectID,
  343.     UInt32                        *pClientData);
  344.  
  345. OSStatus    FWSetSBP2NormalCommandGeneration (
  346.     FWCommandObjectID            fwCommandObjectID,
  347.     UInt32                        generation);
  348.  
  349. OSStatus    FWGetSBP2NormalCommandGeneration (
  350.     FWCommandObjectID            fwCommandObjectID,
  351.     UInt32                        *pGeneration);
  352.  
  353. OSStatus    FWSetSBP2NormalCommandParams (
  354.     FWCommandObjectID            fwCommandObjectID,
  355.     UInt32                        bufferCount,
  356.     FWAddress                    *bufferPtrList,
  357.     UInt32                        *bufferLengthList,
  358.     Ptr                            commandBuffer,
  359.     UInt32                        commandLength,
  360.     UInt32                        normalFlags,
  361.     UInt32                        maxPayloadSize,
  362.     Duration                    timeoutDuration,
  363.     UInt32                        clientData);
  364.  
  365. OSStatus    FWGetSBP2NormalCommandParams (
  366.     FWCommandObjectID            fwCommandObjectID,
  367.     FWCommandObjectID            *pFWLoginCommandObjectID,
  368.     UInt32                        *pBufferCount,
  369.     FWAddress                    *bufferPtrList,
  370.     UInt32                        *bufferLengthList,
  371.     Ptr                            commandBuffer,
  372.     UInt32                        *pCommandLength,
  373.     UInt32                        *pNormalFlags,
  374.     UInt32                        *pMaxPayloadSize,
  375.     Duration                    *pTimeoutDuration,
  376.     UInt32                        *pClientData);
  377.  
  378. OSStatus    FWGetSBP2NormalCommandObjectIDFromORB_POINTER (
  379.     FWCommandObjectID            fwLoginCommandObjectID,
  380.     FWAddress                    ORB_POINTER,
  381.     FWCommandObjectID            *pFWCommandObjectID);
  382.     
  383. OSStatus    FWAppendSBP2Command (
  384.     FWCommandObjectID            fwCommandObjectID);
  385.  
  386. OSStatus    FWAllocateSBP2ManagementCommandObject (
  387.     FWReferenceID                fwReferenceID,
  388.     FWCommandObjectID            *pFWCommandObjectID);
  389.  
  390. OSStatus    FWSetSBP2ManagementCommandFunction (
  391.     FWCommandObjectID            fwCommandObjectID,
  392.     UInt32                        function);
  393.  
  394. OSStatus    FWGetSBP2ManagementCommandFunction (
  395.     FWCommandObjectID            fwCommandObjectID,
  396.     UInt32                        *pFunction);
  397.  
  398. OSStatus    FWSetSBP2ManagementCommandCommandID (
  399.     FWCommandObjectID            fwManagementCommandObjectID,
  400.     FWCommandObjectID            fwCommandObjectID);
  401.  
  402. OSStatus    FWGetSBP2ManagementCommandCommandID (
  403.     FWCommandObjectID            fwManagementCommandObjectID,
  404.     FWCommandObjectID            *pFWCommandObjectID);
  405.  
  406. OSStatus    FWSetSBP2ManagementCommandResponseBuffer (
  407.     FWCommandObjectID            fwCommandObjectID,
  408.     Ptr                            responseBuffer,
  409.     UInt32                        maxResponseSize);
  410.  
  411. OSStatus    FWGetSBP2ManagementCommandResponseBuffer (
  412.     FWCommandObjectID            fwCommandObjectID,
  413.     Ptr                            *pResponseBuffer,
  414.     UInt32                        *pMaxResponseSize);
  415.  
  416. OSStatus    FWSBP2Login (
  417.     FWCommandObjectID            fwCommandObjectID);
  418.  
  419. OSStatus    FWSBP2Logout (
  420.     FWCommandObjectID            fwCommandObjectID);
  421.  
  422. OSStatus    FWSBP2Manage (
  423.     FWCommandObjectID            fwCommandObjectID);
  424.  
  425. OSStatus    FWGetSBP2LUNFromFWReferenceID (
  426.     FWReferenceID                fwReferenceID,
  427.     UInt32                        *pLUN);
  428.  
  429. // Not SBP-2 specific - move near similar calls.
  430.  
  431. OSStatus    FWAllocateFWCommandObjectMemory (
  432.     FWCommandObjectID            fwCommandObjectID,
  433.     UInt32                        byteCount);
  434.  
  435. OSStatus FWGetFWReferenceIDFromUniqueID (
  436.     FWReferenceID                fwReferenceID,
  437.     CSRNodeUniqueID                csrNodeUniqueID,
  438.     FWReferenceID                *pFWReferenceID);
  439.  
  440.  
  441.  
  442. #if PRAGMA_ALIGN_SUPPORTED
  443. #pragma options align=reset
  444. #endif
  445.  
  446. #if PRAGMA_IMPORT_SUPPORTED
  447. #pragma import off
  448. #endif
  449.  
  450. #ifdef __cplusplus
  451. }
  452. #endif
  453.  
  454. #endif /* __FIREWIRESBP2__ */
  455.